Refer to the document "Mac OS USB 1.4f3 Readme" in the Documentation folder for a description of the changes between versions of USB.
This DDK requires that you have the Universal Interfaces and Libraries 3.3 installed in your development environment. You can obtain these files from the Apple Developer Connection DDK web page -
<http://developer.apple.com/sdk/index.html>
The two common symptoms that you have not yet installed these files will be:
1. There is a compile time error that the header file "MacErrors.h" could not be found
2. There is a link error that the file HIDLib could not be found.
Both files are included with Universal Interfaces and Libraries 3.3.
System Requirements for USB 1.4f3
---------------------------------
Apple is formally qualifying USB 1.4f3 on the Macintosh systems with built-in USB and SSW 9.0 installed. You can also test with Mac OS 8.6, however, USB Audio devices are not supported except with Mac OS 9.0 and only on Macintosh systems with built-in USB. Mac OS USB 1.4f3 will also work with Power Macintosh systems with OHCI-based USB PCI or USB Cardbus cards installed. To test with USB v1.4f3, first install Mac OS 8.6 or 9.0 onto your system, then follow the instructions below.
USB Fundamentals
----------------
For the current generation of Power Macintosh systems, USB is the primary interface for connections to low to medium speed peripheral devices. There are numerous advantages for adopting the USB standard on Macintosh, and they are discussed in the "Mac OS USB DDK API Reference Guide". On the current Macintosh systems there is no ADB or Serial Port connections. USB is be the primary port for connecting low/medium speed peripheral devices to the Macintosh.
The DDK provides the tools, interfaces, system files, and module examples for you to start development of USB products for the Macintosh.
Keeping up to date on Mac OS USB
--------------------------------
To stay abreast with developments on Mac OS USB, check out the Mac OS USB Developer web site for the latest information. As updates to Mac OS USB occur, development releases of the software will be made available from this web site. The URL for the web site is:
<http://developer.apple.com/dev/usb>
You can also subscribe to the Mac OS USB Developer mailing list where development questions regarding Mac OS USB are posed and answered. To submit a question to the mailing list you must first be a subscriber. To subscribe to the mailing list, send an email with the subject field set to "subscribe usb" (omit the double quotes for the message) to requests@isg.apple.com.
USB Alerts to developers are always posted to the mailing list. These alerts are also posted to the Mac OS USB Developer Web site at the following location.
http://developer.apple.com/dev/usb/devalerts.html
Getting started with Mac OS USB
-------------------------------
To develop with Mac OS USB v1.4, you will need a Power Macintosh system with USB built in, or a USB PCI card installed. This release of Mac OS USB also support USB Cardbus card on PowerBook G3 Series system. You should also have SSW 8.6 or greater installed.
USB v1.4 will support PCI USB cards from several vendors. The enclosed software is for developmental purposes and will support USB PCI cards from other vendors, but it is not directly supported by Apple, nor is it intended for end-users. End-user customers are encouraged to download the standalone USB Adapter Card Support Installer rather than use the extensions provided in this DDK.
You may find that development on a Power Mac system with a USB PCI card and serial port, is easier, as you can use the Power Mac Debugger with a second Power Macintosh system. A Power Macintosh system with ADB keyboard is useful for debugging with Macsbug, since there are cases when the system cannot process keystrokes from a USB keyboard.
Installing the Mac OS USB Software
----------------------------------
Before using the enclosed software on a Macintosh system with built-in USB you must already have the Mac OS USB 8.6 or greater present. If the Mac OS ROM file includes this release of USB, do not install the system extension components from this DDK to the Extensions Folder.
To install the USB System Software components,
1. remove all files with the following names from your Extensions Folder,
USB Support,
USB Device Extension,
USBCompositeDriver,
USBFamilyExpert,
USBHIDKeyboardModule,
USBHIDMouseModule,
USBHIDUniversalModule,
USBHubDriver0,
USBHubDriver1,
USBOpenHCIDriver,
USBPrintDriver,
USBCommClass,
SerialShimLib,
HID Library,
USB Software Locator,
USB Power Class,
USB Mass Storage Extension,
USB Mass Storage Support
2. drag copy the contents of the folder
:Extensions-AppleBuilt:
to the Extensions folder.
3. Before you reboot, modify the file "USB Support" to include a new resource 'usbx' (Resource ID = 1984). Without this resource, this release of USB will not load. The following alert is raised to indicate that the resource is not present.
4. Reboot your system after making this modification.
Important Notes on Installation and Use of this DDK software
This DDK will let you look at the sources to some working class drivers, build the examples, and develop & build your own code.
Please remember that these driver samples are Copyright Apple Computer, Inc.. You may use the supplied code to develop Class Drivers for your devices. As for publishing the source code, please
check first with the Mac OS USB DDK License agreement, included in this DDK.
The current driver samples may, reflect the latest state of the art of driver writing for USB in the Mac OS. Note that the PrinterClassModule and the USBSampleStorageDriver samples are for example purpose only. These samples are the basis for the real drivers, however we are unable to provide the actual class driver code. The remaining examples are the real code for the Keyboard HID, Mouse HID, Universal HID, and Composite class drivers which will ship on the iMac
While not extensively tested (by the development team), the sample sources have been tweaked slightly to make builds under CodeWarrior some what less problematic. The project files
are provided to help jumpstart your development process.
Using the Mac OS USB DDK under MPW
----------------------------------
For previous releases of the USB DDK, we provided a current UserStartup•USBDDK and makefiles for each of the sample class drivers. As there are very few developers who program with the MPW environment and to expidite the release of this DDK, we do not provide make files for the class driver samples, nor UserStartup files for MPW.
If MPW is your primary development platform and you need a make file for one of the example class drivers, submit a request to the Mac OS USB mailing list and a sample make file, if available for the example, will be sent to you. See the section "Keeping up to date on Mac OS USB" above for information on how to subscribe to the Mac OS USB Developer mailing list.
If you do use MPW, you must update your libraries and Interfaces to Universal Interfaces and Libraries v3.3b1 or later.
Using the Mac OS USB DDK with MetroWerks CodeWarrior
We have supplied MetroWerks CodeWarrior project files for all of the USB Modules code examples. All of the project files were created using CodeWarrior Pro 1, IDE 2.0. The
project files are also compatible with CodeWarrior Pro IDE 2.1, 3.0 and later.
For the CodeWarrior IDE environments v2.0 - v3.0, you must use the Universal Interface & Libraries v3.3b1. The examples will not build using the interfaces supplied with the CodeWarrior 2.0 - v5.0 environments. The URL for the Developer Development Kits web page is
<http://developer.apple.com/sdk/>
As mentioned for MPW, it is highly recommend that you use one Macintosh for coding purposes and one Mac (aka "Target" system) for checkout/testing purposes.
The supplied project files will place the built drivers and extensions into the Target folder of the DDK.
If your driver is not immediately recognized, check the PPC Linker settings panel that
Installing the Mac OS USB DDK for CodeWarrior for the First Time
0. Ensure that you have the Universal Insterface & Libraries 3.3b1 installed
in your CodeWarrior environment.
1. Copy the files USB.h and HID.h included in this SDK to the
":Mac OS Support:Headers:Universal Headers:" folder. Do not
use these header files from an earlier USB DDK with the
supplied project files, as the examples may not build.
2. If you experience compiler errors with the program samples,
check whether you have updated the USB.h and HID.h header files in the
":Mac OS Support:Headers:Universal Headers:" folder.
3. You will need to create a folder by the name
":Extensions-MCWBuilt"
If this folder does not exist, or the folder name is different,
the class driver samples will be created in the CodeWarrior folder.
Using the CodeWarrior Project Files
---------------------------------
For the following samples, there is only a single target for
each project:
CompositeClassDriver
KeyboardModule
MouseModule
UniversalModule
USBKeypad
USBModem
USBTabletModule
For the PrinterClassDriver example, compile the targets in
the following order
1. PrinterClassDRVR - creates the 68K DRVR resource
2. PrintClassDriver - creates the USB PrintClassDriver module
3. ChooserPack.rsrc - creates the "PACK" resource
4. USB Chooser Driver - creates the Chooser extension for the
USB printer
For the USBSampleStorageDriver example, compile the targets in
the following order
1. USBStorageClassDriver - creates the USB StorageClassDriver module
2. USBStorageClassShim - creates the shim module which loads the unit
table driver when the device is attached
USBStorageClassUTDriver - auto built into shim - native driver
compiled as a resource into shim file.
Known Issues
------------
The following is a list of known issues with this release of the USB DDK.
- If you install this release of USB 1.4f3 directly without adding the 'usbx' (ID = 1984) resource, then USB will not load and an alert message is displayed. Refer to the instructions above in section "Installing the Mac OS USB Software" on how to modify the "USB Support" file so that it will function correctly.
- The USBSampleStorageDriver does not correctly demonstrate how to handle a hot unplug situation. This sample will be updated to demonstrate how this situation should be properly handled. The existing sample sets up a Timer Task which when fired makes a call to SystemTask. The call to SystemTask is not supported from an interrupt context.
- Apple USB Audio support will only function on Macintosh systems with built-in USB AND with Mac OS 9.0 or greater installed. The Sound Manager components required to support the USB Audio devices are built into the Mac OS ROM file, which is not accessible by Macintosh systems that do not have USB built-in.
Contact / Marketing Information
-------------------
Mac OS USB DDK Upgrades and latest information:
For the latest information on the Mac OS USB DDK, refer to the Mac OS USB web page. The latest shipping and pre-release versions of Mac OS USB will be accessible there.
<http://developer.apple.com/hardware/usb/>
Check the Developer Development Kits web page for other DDKs which you may need. The web page is
<http://developer.apple.com/sdk/>
For Bug Reports:
To ensure the appropriate data is collected, please use the Bug Reporter
to send us your bug reports. The Bug Reporter can be found at:
<http://developer.apple.com/bugreporter>
When reporting problems, please include the machine configuration,
including the vendor of the PCI USB card which you have tested with.
For Technical Questions:
For generic Mac OS USB questions, submit them to the Mac OS USB
Developer mailing list. Refer to the section above "Keeping up to date
on Mac OS USB" for information on how to subscribe to this mailing list.
Often questions can be answered by someone on the mailing list.
If your question is not answered on the mailing list, or if your question
is proprietary, contact Worldwide Developer with purchased development-level
technical support incidents at
<mailto:dts@apple.com>
Technical support incidents are bundled in our Premier and Select
Developer programs. For information about joining our programs,
please visit our Apple Developer Connection web site at
